R Markdown Tutorial

Holly Zaharchuk

February 02, 2022

What is R Markdown?

  • Markdown is a specific markup language with plain text-formatting syntax
  • R Markdown is a type of markdown language
  • R Markdown combines R code (or code from other programming languages) and markdown in the RStudio integrated development environment (IDE)

What will we talk about today?

  1. Components of an R Markdown document
  2. Output options
  3. Content
  4. Formatting
  5. Trouble-shooting

General tips

  • Treat your data as read-only
  • Comment code early and often
  • Keep code chunks small
  • Label chunks to help with diagnosing issues
  • Nest all files under one directory (if possible)

Parts of an R Markdown document

  1. YAML header
  2. Markdown
  3. Code chunks

YAML header

  • The first part of your document is called the YAML header
  • This is where you set global options for the output type and formatting
  • This header is set apart from the rest of the document by three dashes
---
title: "Why R Markdown Is the Best"
author: "Me"
output: html_document
---

Markdown

Plain text-formatting allows for conversion to different document types

1. People
1. Order
1. Our
1. Patties
  1. People
  2. Order
  3. Our
  4. Patties

Code chunks

  • Code chunks are set apart from markdown by three backticks at the beginning and end
  • In curly brackets after the first set of backticks, you specify the coding language you want to use
  • You can also add other arguments in the curly brackets
```{r example}
## Load packages ##

# Package list
pkg_list <- c(tidyverse", "ggplot2", "kableExtra", "patchwork")

# Load packages
pacman::p_load(pkg_list, character.only = TRUE)
```

Code chunks (continued)

To test your code chunks, you can:

  • Highlight the relevant lines of code and hit CTRL/command + enter
  • Hit the green play button in the upper right-hand corner of the chunk
  • Use the Run dropdown menu at the top right of the document

Creating output

Output types

  • HTML: most flexible
  • PDF: requires \(\LaTeX\) to compile (TinyTeX distribution)
  • Microsoft Office (Word/Powerpoint): most convenient for collaboration

YAML specification

  • Use the output argument in the YAML header
  • Pay attention to indentation and colons
  • Press the knit button or command/CTRL + shift + K

Render

  • Render files in the console with rmarkdown::render(file, output_format)
  • Create PDF from HTML with pagedown::chrome_print(file)

Using output templates

  1. Built-in templates
  2. Templates from R packages
  3. User-defined templates

Built-in templates

  • Documents
    • html_document
    • pdf_document
    • word_document
  • Presentations
    • ioslides_presentation and slidy_presentation for HTML
    • beamer_presentation for PDF
    • powerpoint_presentation
  • Interactive Shiny documents and presentations

R package templates

\(\LaTeX\)  templates

---
output:
  pdf_document:
    template: plos_latex_template.tex
---

Word document templates

Go to the Styles Pane in Word, format, and “Update to Match Selection”

---
output:
  word_document:
    reference_docx: template.docx
---

Content

  • R Markdown documents include the markdown text itself, as well as output from code chunks
  • Code chunks can output data, graphs, tables, and images
  • You can also reference variables from code chunks in markdown text

Markdown

Inline R

# Pull species column from iris and get unique values in column
species <- iris %>% pull(Species) %>% unique()

# Get number of unique species
species_count <- length(species)
  • I can report that there are 3 species without writing out the number itself with `r species_count`
  • I can also reference report the exact species names with`r species`: setosa, versicolor, virginica

Formatting

  1. YAML parameters and references
  2. Inline \(\LaTeX\) and CSS code
  3. Custom edits to templates
  4. Custom functions

YAML parameters

General YAML parameters

---
title: |
  <center> A very impressive title: </center>
  <center> An equally impressive subtitle </center>
---

YAML references

  • Bibliography: .bib (I use BibDesk for my reference manager)
  • Citation style language: .csl
  • \(\LaTeX\) styling: .cls
  • HTML styling: .css
  • Interacting with pandoc: .lua (multiple bibliographies)

Inline \(\LaTeX\)  and CSS code

  • \(\LaTeX\) with PDFs
    • Calling \(\LaTeX\) packages
    • Using symbols
    • Using type-setting commands (e.g., \vspace{12pt})
  • CSS with HTML

Editing templates

  1. Find out where your R packages “live” by calling installed.packages()
  2. If the template generates a style document (e.g., .cls) in the directory with your .Rmd file, you can edit that without going to the package

Custom functions

Trouble-shooting

Identifying issues

  1. Warnings vs. errors
  2. RStudio vs. R Markdown environments
  3. Package issues
  4. Strategies for troubleshooting issues

Warning

Warning example

Chunk error

Error example

Markdown/YAML error

Error example

Environments

R code and environments

# Define new variable y
y <- 100

# When I run this chunk, I get the expected output (150),
# but it fails when I try to knit the document
# I've set eval=FALSE for this chunk, so it doesn't try to run and prevent my document from knitting
print(x + y)

Package specification

  • Different packages can have the same name for different functions, creating a name-space conflict
  • Tell R which package to look in with package::function notation

Updates

  • Update your TeX distribution from the command line
  • Update all packages (including rmarkdown) in your library with update.packages(path)
  • Update individual packages with install.packages("package")
  • Update R in the console with the updateR package
  • Re-download RStudio to update

Reset your R environment

  • Clear all variables by running rm(ls = list()) in the console
  • Restart your R environment with CTRL/(control + fn) + shift + F10
  • Run all chunks individually in order before compiling to test code

Search for information

  • Use the Help window in RStudio
  • Search for the package in the console with ?package or ??package
  • Google the error you’re getting with the package or function you’re trying to use

Takeaways

  1. YAML header: define output types, templates, and additional parameters
  2. Setup chunk: define global chunk options
  3. Markdown: add information/descriptions and control local text behavior with \(\LaTeX\)/CSS (depending on output)
  4. Chunks: add R code and control local chunk behavior

Reference documents

Other packages/tools

Questions?